ref(onboarding): Introduce content blocks #95224

ArthurKnaus · 2025-07-10T13:21:06Z

Introduce specialized content blocks opposed to the current configuration object.
This makes it clearer what is rendered in which order and which properties are required -> enforced by types.
Converted react and java project creation onboarding docs. (also removed not-needed profiling content from react docs)

part of TET-761: Docs: Move from configuration objects to content blocks

ArthurKnaus · 2025-07-10T13:23:58Z

static/app/components/onboarding/gettingStartedDoc/onboardingCodeSnippet.tsx

+  const partialLoading = useMemo(
+    () => children.includes(PACKAGE_LOADING_PLACEHOLDER),
+    [children]
+  );


Previously we had a separate prop partiallyLoading on the configuration object, which was missing most of the time. I decided to drop it from the new format and rather autodetect the loading placeholder in the snippet. This solution is maybe a bit hacky but is much better DX when writing docs.

ArthurKnaus · 2025-07-10T13:25:36Z

static/app/components/onboarding/gettingStartedDoc/types.ts

+   *
+   * **Do not** use this with custom react elements but instead use the `custom` block type.
+   */
+  text: React.ReactNode;


Would love to only have string here. Also the translation functions are making the docs so much harder to read...

codecov · 2025-07-10T13:26:26Z

Codecov Report

All modified and coverable lines are covered by tests ✅

✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##           master   #95224   +/-   ##
=======================================
  Coverage   87.84%   87.85%           
=======================================
  Files       10469    10469           
  Lines      605374   605361   -13     
  Branches    23674    23672    -2     
=======================================
- Hits       531819   531814    -5     
+ Misses      73195    73187    -8     
  Partials      360      360

ArthurKnaus · 2025-07-10T13:29:21Z

static/app/components/onboarding/gettingStartedDoc/types.ts

+export type ContentBlock =
+  | TextBlock
+  | CodeBlock
+  | CustomBlock
+  | AlertBlock
+  | ConditionalBlock;


I just added the most basic ones that I encountered while converting java & react docs.
In the future we will for sure add more like heading, list, ...

ArthurKnaus · 2025-07-10T13:32:02Z

static/app/components/onboarding/gettingStartedDoc/utils/index.tsx

+        type: 'custom',
+        content: (
+          <OnboardingCodeSnippet
+            language="bash"
+            onCopy={() =>


onCopy and onSelectAndCopy was only supported for this one usage. Decided to resort to a custom block instead of bloating the interface.

priscilawebdev · 2025-07-11T08:22:51Z

static/app/gettingStartedDocs/javascript/react.tsx

-import {
-  getProfilingDocumentHeaderConfigurationStep,
-  MaybeBrowserProfilingBetaWarning,
-} from 'sentry/components/onboarding/gettingStartedDoc/utils/profilingOnboarding';


good catch removing profiling 🎉

yeah there is even more to do here! will create a ticket for it

static/app/components/onboarding/gettingStartedDoc/contentBlocks/defaultBlocks.tsx

priscilawebdev · 2025-07-11T08:45:49Z

static/app/components/onboarding/gettingStartedDoc/contentBlocks/defaultBlocks.tsx

+`;
+
+function TextBlock(block: Extract<ContentBlock, {type: 'text'}>) {
+  return <TextBlockWrapper>{block.text}</TextBlockWrapper>;


Suggested change

return <TextBlockWrapper>{block.text}</TextBlockWrapper>;

return <div css={css`${baseBlockStyles} code:not([class*='language-']) {

color: ${p => p.theme.pink400};

}`}>{block.text}</div>;

👍 though I will move the style definition out of the render function so they are not serialized on every render

ah no, it needs the theme so I cant transform it to css

you can use useTheme

tbh i find <TextBlockWrapper>{block.text}</TextBlockWrapper> way nicer and easier to work with then

<div css={css`${baseBlockStyles} code:not([class*='language-']) { color: ${p => p.theme.pink400}; }`}>{block.text}</div>;

I don't have have a strong opinion here, but I am always in favour of having less code

Out of curiosity, I checked the implementation of styled. ~~It always serializes styles during render.~~
So from a performance view, static styles should be faster with the css annotation outside the component. But as soon as you use the theme or props inside the css it does not make a difference (at least with regards to style serialization).
Edit: My bad did not see that styled already implements a cache based on the template result. Same goes for the css prop handling. So no difference.

priscilawebdev · 2025-07-11T09:06:36Z

static/app/components/onboarding/gettingStartedDoc/contentBlocks/defaultBlocks.tsx

+export const defaultBlocks: BlockRenderer = {
+  text: TextBlock,
+  code: CodeBlock,
+  custom: CustomBlock,


I am a bit confused about having a customBlock inside of defaultBlocks. is it a default custom block?

If i get this correctly it is a block component that is used by default when the type of the block is custom.

yes, it is the default renderer for the block with type custom and just adds a wrapper div with margin so devs writing some custom jsx in the docs do not have to care about the spacing between content.

the block type custom is meant as the escape hatch if no other blocks fit:

/** * Custom blocks can be used to render any content that is not covered by the other block types. */ type CustomBlock = BaseBlock<'custom'> & { content: React.ReactNode; };

yes I get that, just the name is confusing

maybe it helps renaming defaultBlocks to defaultRenderers 🤔

priscilawebdev

This PR has quite a few changes, which made it difficult to review...though I understand it was probably needed for the proof of concept. I’ve gone through all the code, and it looks really good. I especially like the comments you added to the new props and how you marked the old ones as deprecated. I also compared the rendered components to what we have in production, and everything seems just right. Nice work! 🚀

It might take me and maybe others a little time to get used to the new content blocks, but I think they’ll make our code cleaner and easier to work with.

obostjancic

JonasBa · 2025-07-12T13:24:35Z

static/app/components/onboarding/gettingStartedDoc/contentBlocks/defaultRenderers.tsx

+const baseBlockStyles = css`
+  :not(:last-child) {
+    margin-bottom: var(${CssVariables.BLOCK_SPACING});
+  }
+`;


Can you use a <Alert.Container> here? It should add the margin for you

JonasBa · 2025-07-12T13:27:12Z

static/app/components/onboarding/gettingStartedDoc/contentBlocks/utils.tsx

+  ContentBlock,
+} from 'sentry/components/onboarding/gettingStartedDoc/contentBlocks/types';
+
+export enum CssVariables {


Why not use a styled component here?

I would suggest finding a more specific naming here given that these are exported, you wouldn't want them to pollute LSP suggestions.

ArthurKnaus added 2 commits July 10, 2025 15:10

ref(onboarding): Introduce content blocks

c98989b

remove heading styles from text block

3ad0b8a

github-actions bot added the Scope: Frontend Automatically applied to PRs that change frontend components label Jul 10, 2025

ArthurKnaus commented Jul 10, 2025

View reviewed changes

explain casting on the RendererComponent

c33ce48

vercel bot deployed to Preview July 10, 2025 13:40 View deployment

support content blocks in performance and agent monitoring onboarding

d9e8a64

vercel bot deployed to Preview July 10, 2025 14:34 View deployment

split content block related code into separate folder

3a38cd0

vercel bot deployed to Preview July 11, 2025 07:23 View deployment

ArthurKnaus added 2 commits July 11, 2025 09:23

use css var enum

4cab177

adjust comment

c856a91

vercel bot deployed to Preview July 11, 2025 07:26 View deployment

ArthurKnaus marked this pull request as ready for review July 11, 2025 07:27

ArthurKnaus requested review from a team as code owners July 11, 2025 07:27

This comment was marked as outdated.

Sign in to view

remove String() from key

7f322b3

vercel bot deployed to Preview July 11, 2025 07:45 View deployment

This comment was marked as outdated.

Sign in to view

priscilawebdev reviewed Jul 11, 2025

View reviewed changes

priscilawebdev approved these changes Jul 11, 2025

View reviewed changes

obostjancic approved these changes Jul 11, 2025

View reviewed changes

apply review feedback

01529f0

vercel bot deployed to Preview July 11, 2025 09:59 View deployment

This comment was marked as outdated.

Sign in to view

fix typo

0e589ae

vercel bot deployed to Preview July 11, 2025 10:53 View deployment

This comment was marked as spam.

Sign in to view

JonasBa reviewed Jul 12, 2025

View reviewed changes

-  return <TextBlockWrapper>{block.text}</TextBlockWrapper>;
+  return <div css={css`${baseBlockStyles}  code:not([class*='language-']) {
+    color: ${p => p.theme.pink400};
+  }`}>{block.text}</div>;

Uh oh!

ref(onboarding): Introduce content blocks #95224

Are you sure you want to change the base?

ref(onboarding): Introduce content blocks #95224

Conversation

ArthurKnaus commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

priscilawebdev Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ArthurKnaus Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ArthurKnaus Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

priscilawebdev left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

obostjancic left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as spam.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ArthurKnaus commented Jul 10, 2025 •

edited

Loading

codecov bot commented Jul 10, 2025 •

edited

Loading

priscilawebdev Jul 11, 2025 •

edited

Loading

ArthurKnaus Jul 11, 2025 •

edited

Loading

ArthurKnaus Jul 11, 2025 •

edited

Loading

priscilawebdev left a comment •

edited

Loading